Software Vault: The Diamond Collection/The Diamond Collection (Software Vault)(Digital Impact).ISO/cdr43/ppl4p10.zip/SCRIPTS.DOC

Text File | 1995-02-12 | 23KB | 953 lines

                    BUILDER (Script Compiler)

                 For the Personal Protocol Library


                          USERS MANUAL





                           Version 2.0

                        February 12, 1995




                 This software is provided as-is.
          There are no warranties, expressed or implied.




                       Copyright (C) 1995
                       All rights reserved



                       MarshallSoft Computing, Inc.
                       Post Office Box 4543
                       Huntsville AL 35815

                       Voice 205-881-4630
                       FAX   205|880|0925
                       BBS   205-880-9748




                              _______
                         ____|__     |                (R)
                      --+       |    +-------------------
                        |   ____|__  |  Association of
                        |  |       |_|  Shareware
                        |__|   o   |    Professionals
                      --+--+   |   +---------------------
                           |___|___|    MEMBER
















 SCRIPTS Users Manual                                              Page 1
                       C O N T E N T S





  Chapter                                                      Page

  1.0 Introduction................................................3
      1.1  Running BUILDER........................................3
      1.2  Script Language........................................4
  2.0 Architecture................................................5
  3.0 Script Instructions.........................................6
      3.1  Pseudo Instruction.....................................6
      3.2  Instruction Set........................................6
           3.2.1  ACCEPT..........................................6
           3.2.2  BAUD............................................6
           3.2.3  CALL............................................7
           3.2.4  DATABITS........................................7
           3.3.5  DEBUG...........................................7
           3.2.6  DELAY...........................................7
           3.2.7  GOTO............................................7
           3.2.8  HALT............................................7
           3.2.9  HANGUP..........................................7
           3.2.10 IF..............................................8
           3.2.11 IFFALSE.........................................8
           3.2.12 IFTRUE..........................................8
           3.2.13 IFNOT...........................................8
           3.2.14 LOOP............................................8
           3.2.15 NOP.............................................8
           3.2.16 PARITY..........................................9
           3.2.17 PROTOCOL........................................9
           3.2.18 QUIET...........................................9
           3.2.19 RECEIVE.........................................9
           3.2.20 REPLY...........................................9
           3.2.21 RETURN..........................................9
           3.2.22 SAY............................................10
           3.2.23 SEND...........................................10
           3.2.24 SETCASE........................................10
           3.2.25 SETCOUNT.......................................10
           3.2.26 SETPACE........................................10
           3.2.27 SETWAIT........................................10
           3.2.28 STATUS.........................................10
           3.2.29 STOPBITS.......................................11
           3.2.30 TEST...........................................11
           3.2.31 USER...........................................11
           3.2.32 WAITFOR........................................11
  4.0 Example Script.............................................12



















 SCRIPTS Users Manual                                              Page 2
  1.0 Introduction

  SCRIPT is a simple and easy to use  script  language.   It  is  meant  as  a
  straight  forward  way  to  automate  calling  a  BBS and similar jobs.  The
  program BUILDER compiles script source files and  creates  script  binaries,
  which  can then be executed by the script interpreter SI (or WSI), which can
  be linked with your application. The TERM example application can run script
  files.

  Several example SCRIPT programs are included:

        LOGIN.SS      Logs onto our support BBS as GUEST.

        GET_BUGS.SS   Logs onto our support BBS as  GUEST  and  downloads  the
                      BUGS.DOC file.

        GET_MAIL.SS   Logs onto our support BBS as  GUEST  and  downloads  any
                      new mail addressed to GUEST.

  1.1 Running BUILDER

  The BUILDER executable program is not SHAREWARE, but rather is software that
  is  part  of  the  Personal Protocol Library shareware registration package.
  BUILDER is only available to registered users of the Personal Communications
  Library or Personal Protocol Library.

  To use BUILDER, first write your script using any text editor and  name  the
  file with an extension of ".SS". Compile by typing

       BUILDER <filename>

  where  <filename>  is  specified  without the ".SS" extension. A listing can
  also be displayed by typing

       BUILDER -l <filename>

  An unassembly of the generated script binary can be selected by typing:

       BUILDER -u <filename>

  A detailed debug compilation listing can be selected by typing:

       BUILDER -d <filename>

  For  example, to compile the example script LOGIN.SS with both a listing and
  an unassembly, type:

       BUILDER -lu LOGIN

  The script interpreter (SI or WSI) calls functions in the  MODEM_IO.C  file.
  To  enable  script  interpretation, define SCRIPTS as 1 in the TERM.CFG (for
  PPL4C), DEFINES.PAS (for PPL4P), DEFINES.BAS (for PPL4PB),  or  TERM.H  file
  (for PPL4W).

  BUILDER reads the  script  source  file  with  an  extention  of  ".SS"  and
  generates a script binary file with an extention of ".SB".











 SCRIPTS Users Manual                                              Page 3
  1.2 Script Language

  Use  any  text  editor  to  prepare  a script source file.  A script program
  consists of one or more lines, each line containing either a comment  (lines
  starting  with  a  '#'),  or an instruction. An instruction will have either
  zero or one operand. The optional label precedes the  instruction  and  ends
  with  a colon. Labels and symbols may be up to 50 characters in length. Data
  operands should be delimited by double quote (") characters.  For example:

       # send Control-X 5 times
          SAY      "Sending Control-X 5 times"
          SETCOUNT  5
       AGAIN:
          REPLY     "^X"
          LOOP      AGAIN

  The basic syntax of SCRIPT is

      {label:} opcode {operand}

  where label is optional except for storage or string operations, and operand
  depends on the  particular  instruction.  Some  instructions  such  as  CALL
  require no operand while others such as ACCEPT require a single operand.

  Two  instructions  IF  and IFNOT can make use of the keyword THEN:

      {<label1>:} IF <string> THEN <label2>

  and

      {<label1>:} IFNOT <string> THEN <label2>

  All time values are specified in terms of decimal seconds.  Refer to  QUIET,
  WAITFOR, DELAY, and SETPACE.

  Labels must end with a colon and be separated from the following instruction
  by one or more blanks.

  The END statement is optional and terminates script translation even  though
  more instructions may follow.

  Control characters may be sent by use of the ^ notation where ^A is  1  hex,
  ^B  is  2 hex, etc. In particular, a carriage return (CR) is a ^M and a line
  feed (LF) is a ^J.  In the REPLY instruction (sending a string to the serial
  port), exclamation marks "!" are replaced with carriage returns.

  Scripts are very easy to write.  Refer to the  example  script  segments  in
  Section 3 and the example script in section 4.



















 SCRIPTS Users Manual                                              Page 4
  2.0 Architecture

  The SCRIPT compiler BUILDER translates the source script language into a set
  of instructions and storage for a virtual computer,  which  the  SI  routine
  executes by interpretation.

  The  primary  consideration in designing the virtual machine architecture is
  that it should  be  fast  and  easy  for  the  script  interpreter  (SI)  to
  interpret.   For  this  reason, a large or complex instruction set was ruled
  out. A secondary consideration  is  that  the  virtual  language  should  be
  exceedingly easy to program given the simple instruction set.

  The  virtual  machine consists of a byte addressable code area of 1024 bytes
  and a byte  addressable  data  area  of  1024  bytes.  The  virtual  machine
  instructions  generated  by  BUILDER  are  stored in the code area while the
  string and storage data is stored in the data area.

  There  are  two classes of instructions: those that allocate storage (STRING
  and  STORAGE)  and  executable  instructions.  There   are   41   executable
  instructions in the script language.

  There  are  three  types of instructions: Those that reference the code area
  such as GOTO, those that reference the data area such as ACCEPT,  and  those
  that reference neither such as NOP.

  Every  instruction  that  references  the data area sets the "Program Status
  Character" (PSC) to the first character of the string. A NULL (0 hex) is set
  for empty (NULL) strings.

  The PSC is tested against when doing branch instructions.

      IFTRUE  <label>           ++jumps to <label> if the PSC is not 0
      IFFALSE <label>           ++jumps to <label> if the PSC is 0
      IF <char> THEN <label>    ++jumps to <label> if PSC = <char>
      IFNOT <char> THEN <label> ++jumps to <label> if PSC != <char>


  For example:

      WAITFOR   "R)un Q)uit"
      IFFALSE   TIMED_OUT
      IF "0"    GOT_RUN
      IF "1"    GOT_QUIT
























 SCRIPTS Users Manual                                              Page 5
  3.0 Script Instructions

  3.1 Pseudo Instructions

  There  are  two  classes  of  SCRIPT instructions. The first consists of two
  (pseudo) instructions STRING and STORAGE. They allocate storage in the  data
  area but generate no instructions.

  3.1.1 STRING

  The STRING pseudo instruction stores a string in the data memory.

  <label>: STRING  "<string>"

  Example:

      FILENAME: STRING "MSC_Z.SS"

  3.1.2 STORAGE

  The  STORAGE  pseudo  instruction allocates a range of memory and sets it to
  zeros (NULLs).

  <label>: STORAGE  <size>

  Example:

      FILENAME: STORAGE  15

  3.2 Instruction Set

  The following are the script instructions. Each instruction  either  has  no
  argument or a single argument, which is either a data reference (such as SAY
  or REPLY) or a code reference (such as GOTO).

  3.2.1 ACCEPT

  The ACCEPT instruction accepts a text string from the keyboard.

       FILENAME:   STORAGE    15
                   ...
                   ACCEPT     FILENAME

  Be  sure  that  you  have allocated sufficient storage to accept whatever is
  typed in. ACCEPT can also read into a STRING. The PSC is set to the 1st byte
  of the typed in string.

  3.2.2 BAUD

  The BAUD instruction sets the baud rate (300 to 115200 baud).  The  argument
  is the baud rate.

       BAUD 38400














 SCRIPTS Users Manual                                              Page 6
  3.2.3 CALL

  The CALL instruction calls a script subroutine, which then returns using the
  RETURN instruction. The argument is a program label.

       CALL <my_sub>

  The call stack can accomodate up to 32 subroutine levels.

  3.2.4 DATABITS

  The  DATABITS  instruction  sets  the  number  of  data  bits to 7 or 8. The
  argument is the number of data bits.

       DATABITS 7

  3.2.5 DEBUG

  The DEBUG instruction turns on certain debugging information. It should only
  be used to provide additional information when reporting a bug.

  3.2.6 DELAY

  The DELAY instuction delays a specified amount of time.  The argument is the
  delay time in (decimal) seconds.

       DELAY 5.0

  3.2.7 GOTO

  The  GOTO  instruction  unconditionally  branches. The argument is a program
  label.

       GOTO END

  3.2.8 HALT

  The  HALT  instruction halts (terminates) the script interpreter and returns
  to the calling program. There is no argument.

       HALT

  3.2.9 HANGUP

  The HANGUP instruction hangs up the modem. There is no argument.

       HANGUP




















 SCRIPTS Users Manual                                              Page 7
  3.2.10 IF

  The IF instruction branches if the PSC (Program Status Character)  is  equal
  to the argument.

       WAITFOR    "more?|Main Menu:"
       IF         "0"  THEN GOT_MORE
       IF         "1"  THEN GOT_MENU

  The IF ... THEN syntax is really a short-hand for

       IF  "<char>"
       GOTO <label>

  where  the GOTO following the IF is only executed if the PSC is equal to the
  specified argument.

  3.2.11 IFFALSE

  The IF instruction branches if the PSC (Program Status Character)  is  equal
  to zero (NULL).

       WAITFOR   "OK"
       IFFALSE   ERROR

  3.2.12 IFNOT

  The  IF  instruction  branches  if the PSC (Program Status Character) is not
  equal to the argument.

       WAITFOR    "more?|Main Menu:"
       IF         "0"  THEN GOT_MORE
       IFNOT      "1"  THEN ERROR_EXIT


  3.2.13 IFTRUE

  The IF instruction branches if the PSC (Program  Status  Character)  is  not
  zero (NULL).

       WAITFOR  "OK"
       IFTRUE   GOT_OK

  3.2.14 LOOP

  The LOOP instruction decrements the loop counter (which can be  set  by  the
  SETCOUNT instruction), and branches if the value is less than or equal to 0.

       # transmit control-X 5 times
       SETCOUNT  5
     AGAIN:
       REPLY     "^X"
       LOOP      AGAIN

  3.2.15 NOP

  The NOP instuction doesn't do anything. There is no argument.

       NOP








 SCRIPTS Users Manual                                              Page 8
  3.2.16 PARITY

  The PARITY instruction sets the parity to either None ("N"), Even  ("E")  or
  Odd ("O"). Only the 1st character of the operand is significant.

       PARITY "N"

  3.2.17 PROTOCOL

  The PROTOCOL instruction sets the protocol  to  ASCII,  XMODEM,  YMODEM,  or
  ZMODEM  for  use  by  subsequent SEND and RECEIVE instructions. Only the 1st
  character of the operand is significant.

       PROTOCOL  "A"     # select ASCII protocol
       PROTOCOL  "X"     # select XMODEM protocol
       PROTOCOL  "Y"     # select YMODEM protocol
       PROTOCOL  "Z"     # select ZMODEM protocol

  3.2.18 QUIET

  The  QUIET  instruction  waits  for a period of silence. The argument is the
  quiet time in (decimal) seconds.

       # wait for 5 seconds of quiet
       QUIET 5.0

  3.2.19 RECEIVE

  The RECEIVE instruction starts an ASCII, XMODEM, YMODEM, or  ZMODEM  receive
  session  dependent  upon  the  setting  of  the  PROTOCOL  instruction.  The
  argument is the filename. A dummy filename should be  specified  for  YMODEM
  and ZMODEM receives.

       RECEIVE   "BUGS.DOC"

  3.2.20 REPLY

  The REPLY instruction sends a string  to  the  modem.  A  '!'  character  is
  interpreted as a carriage return. The argument is the reply string.

       REPLY    "GUEST!"

  Any control character can be embedded in the REPLY string by  specifing  its
  value  using  the  ^  notation.  Recalling that ^M is the same as a carriage
  return, the above REPLY instruction could also be coded as:

       REPLY    "GUEST^M"

  3.2.21 RETURN

  The  RETURN  instruction  returns  from  a  script  subroutine.  There is no
  argument.

       RETURN













 SCRIPTS Users Manual                                              Page 9
  3.2.22 SAY

  The  SAY  instruction  displays a string on the console. The argument is the
  string to display.

       SAY    "All done^M^J"

  Recall that ^M denotes a carriage return and ^J denotes a line feed.

  3.2.23 SEND

  The SEND instruction starts an ASCII, XMODEM, YMODEM, or ZMODEM transmission
  session.  The argument is the filename.

       SEND   MY_FILE

  3.2.24 SETCASE

  The  SETCASE  instruction  determines whether case is significant in WAITFOR
  compares.  The default is TRUE (case sensitive). The argument is either  "T"
  or "F". To turn off case sensitivity:

       SETCASE   "F"

  3.2.25 SETCOUNT

  The  SETCOUNT  instruction  sets the count variable which can be used by the
  LOOP instruction. The argument is the count value.

       SETCOUNT  5

  3.2.26 SETPACE

  The SETPACE instruction sets the pace at which characters are sent by REPLY.
  The default is 0.200 of a second. The argument is the pace time in (decimal)
  seconds.

       SETPACE  0.200

  SETPACE does not apply to protocol transfers.

  3.2.27 SETWAIT

  The SETWAIT instruction sets the timeout time that the  WAITFOR  instruction
  uses.  The default is 30 seconds. The argument is the wait time in (decimal)
  seconds.

       SETWAIT 30.0

  3.2.28 STATUS

  The STATUS instruction displays the status of the script interpreter.  There
  is no argument.

       STATUS












 SCRIPTS Users Manual                                              Page 10
  3.2.29 STOPBITS

  The STOPBITS instruction sets the number  of  stop  bits  to  1  or  3.2.  The
  argument is the number of stop bits.

       STOPBITS 1

  3.2.30 TEST

  The  TEST  instruction  sets the Program Status Character (PSC) to the first
  character of the data argument.

  FILENAME: STRING  "HELLO"
            TEST    FILENAME    #sets PSC to "H"

  Note  that  TEST  will  set  the PSC to 0 (NULL) when used to test a STORAGE
  location that hasn't been stored into.

  3.2.31 USER

  There are eight USER instructions named USER1, USER2, ..., USER8.  Each user
  function   references  the  data  area.   The  functionality  of  each  user
  instruction must be programmed into the SI (or WSI)  script  interpreter  by
  the programmer.

  3.2.32 WAITFOR

  The WAITFOR instruction waits (up to the number of seconds specified by  the
  SETWAIT  instruction) for a specified string coming in over the serial line.
  It then sets the Program Status Character (PSC) as follows:  If  the  string
  was not found, the PSC is set to zero (NULL).  If it was found, then the PSC
  is  set  to "0" for the first (or only) sub-string, "1" for the second, etc.
  Substrings are separated by the "|" character.

  For example:

       WAITFOR  "MIKE|PAM|LAUREN"
       IFFALSE  TIMED_OUT
       IF  "0"  THEN GOT_MIKE
       IF  "1"  THEN GOT_PAM
       IF  "2"  THEN GOT_LAUREN

  Don't follow the last sub-string with a "|".
























 SCRIPTS Users Manual                                              Page 11
  4.0 Example Script

  The following script logs on as GUEST and downloads BUGS.DOC from library  5
  of  our  user support BBS. Note that the GUEST account has ZMODEM set as the
  default protocol. When modifying this script for your own account,  be  sure
  to  specify  a  default  protocol  and change the PROTOCOL variable below to
  match. Choose either XMODEM, YMODEM, or ZMODEM.

  ###############################
  # log onto MSC BBS (TRIBBS)   #
  # compile with builder, ver 2 #
  ###############################
  #
  # define parameters to use
  #
  USER:     STRING "GUEST GUEST!"
  PASSWORD: STRING "GUEST!"
  PROTOCOL: STRING "Z"
  PHONE:    STRING "1,205,880,9748!"
  #
  # Dial phone
  #
    SETPACE  0.2
    SETWAIT  2.0
    REPLY   "!AT!"
    WAITFOR  "OK"
    IFTRUE   DIAL
    SAY      "Expected OK not received"
    GOTO     ERROR
  DIAL:
    SETWAIT  45.0
    REPLY    "ATDT"
    REPLY    PHONE
    WAITFOR  "CONNECT"
    IFTRUE   LOGIN
    SAY      "Expected CONNECT not found"
    GOTO     ERROR
  #
  # no graphics
  #
  LOGIN:
    SETWAIT  30
    REPLY    CR
    WAITFOR  "graphics (y/N)?"
    IFFALSE  ERROR
    REPLY    CR
  #
  # enter name
  #
    WAITFOR  "FIRST and LAST name:"
    IFFALSE  ERROR
    REPLY    USER
  #
  # enter password
  #
    WAITFOR  "password:"
    IFFALSE  ERROR
    REPLY    PASSWORD









 SCRIPTS Users Manual                                              Page 12
  #
  # "more?" or "Main Menu:"
  #
  MORE:
    WAITFOR  "more?|Main Menu:"
    IF       "1" THEN SKIP_MAIN
    IFNOT    "0" THEN ERROR
    REPLY    CR
    GOTO     MORE
  SKIP_MAIN:
    REPLY    CR
  #
  # select Files
  #
    WAITFOR  PROMPT
    IFFALSE  ERROR
    REPLY    "F"
  #
  # select Change
  #
    WAITFOR  PROMPT
    IFFALSE  ERROR
    REPLY    "C"
  #
  # select file area 5
  #
    WAITFOR  "file area:"
    IFFALSE  ERROR
    REPLY    "5!"
  #
  # select Download
  #
    WAITFOR  PROMPT
    IFFALSE  ERROR
    REPLY    "D"
    WAITFOR  "download:"
    IFFALSE  ERROR
    REPLY    "BUGS.DOC!"
    WAITFOR  "download:"
    IFFALSE  ERROR
    REPLY    CR
  #
  # select protocol
  #
    WAITFOR  "protocol:"
    IFFALSE  ERROR
    REPLY    PROTOCOL
    REPLY    CR
    WAITFOR  "to continue:"
    IFFALSE  ERROR
    REPLY    CR
  #
  # download BUGS.DOC
  #
    DELAY    0.25
    PROTOCOL PROTOCOL
    RECEIVE  "BUGS.DOC!"
    SAY      "Download complete"









 SCRIPTS Users Manual                                              Page 13
  #
  # say goodbye
  #
    QUIET    0.5
    REPLY    CR
    WAITFOR  PROMPT
    IFFALSE  ERROR
    REPLY    "G!"
    SAY      "Hanging up..."
    REPLY    CR
    HALT
  #
  # error exit
  #
   ERROR: SAY " "
    SAY "Error !"
    STATUS
    HALT
  #
  # common strings
  #
  PROMPT: STRING  "?]?"
  CR:     STRING  "!"
  #
    END










































 SCRIPTS Users Manual                                              Page 14